# 10 - 多 Agent 与协调器

## 概述

Claude Code 支持多种多 Agent 模式，从简单的子 Agent 生成到复杂的 Agent 团队协调。

---

## 层次结构

```
主 Agent (Main Thread)
  │
  ├── AgentTool → 子 Agent (Sub-agent)
  │     └── 独立的 query 循环，有限的 Tool 集
  │
  ├── Coordinator 模式 → 协调器 + 工人
  │     ├── 协调器 Agent (只有 Agent/Task/SendMessage Tool)
  │     └── 工人 Agent (有 Bash/Read/Edit 等实际 Tool)
  │
  └── Agent Swarms → 团队协作
        ├── TeamCreateTool → 创建 Agent 团队
        ├── SendMessageTool → 团队内通信
        └── TeamDeleteTool → 解散团队
```

---

## 1. AgentTool — 子 Agent

最基础的多 Agent 机制。主 Agent 通过 `AgentTool` 生成子 Agent：

### 工作原理

```
主 Agent: "我需要搜索这个代码库"
  │
  ├── tool_use: AgentTool { prompt: "搜索所有 API 端点" }
  │
  ▼
子 Agent 创建
  ├── 获得独立的消息历史
  ├── 获得受限的 Tool 集（不能再生成子 Agent 等）
  ├── 独立的 query 循环
  └── 执行完成 → 结果返回给主 Agent
```

### 子 Agent 限制

```typescript
// src/constants/tools.ts
export const ALL_AGENT_DISALLOWED_TOOLS = [
  // 子 Agent 不能使用的 Tool
]

export const CUSTOM_AGENT_DISALLOWED_TOOLS = [
  // 自定义 Agent 不能使用的 Tool
]

export const ASYNC_AGENT_ALLOWED_TOOLS = [
  // 异步 Agent 可以使用的 Tool
]
```

子 Agent 的 Tool 集通过 `filterToolsForAgent()` 过滤。

### 上下文隔离

```typescript
// createSubagentContext 创建隔离的上下文
function createSubagentContext(parentContext) {
  return {
    ...parentContext,
    messages: [],           // 新的消息历史
    readFileState: clone(parentContext.readFileState),  // 克隆文件状态
    // setAppState 对异步 agent 是 no-op
  }
}
```

---

## 2. Coordinator 模式

Feature flag: `COORDINATOR_MODE`

### 架构

```
用户请求
  │
  ▼
协调器 Agent
  ├── 只有: AgentTool, TaskStopTool, SendMessageTool
  ├── 负责: 分解任务、分配工作、汇总结果
  │
  ├──→ 生成工人 Agent A
  │     └── 有: Bash, Read, Edit, Glob, Grep...
  │
  ├──→ 生成工人 Agent B
  │     └── 有: Bash, Read, Edit, Glob, Grep...
  │
  └── 等待结果 → 汇总 → 响应用户
```

### 特点

- **职责分离**：协调器不执行实际操作，只负责规划和调度
- **并行执行**：多个工人 Agent 可以并行工作
- **任务通知**：工人通过 XML `<task-notification>` 标签向协调器报告进度

```typescript
// coordinator/coordinatorMode.ts
export function getCoordinatorUserContext(
  mcpClients: ReadonlyArray<{ name: string }>,
  scratchpadDir?: string,
): { [k: string]: string }
```

---

## 3. Agent Swarms — 团队协作

Feature flag: `isAgentSwarmsEnabled()`

### 创建团队

```
TeamCreateTool
  │
  ├── 创建多个 Agent
  ├── 分配角色和任务
  └── 建立通信通道
```

### 团队通信

```
Agent A ──SendMessageTool──→ Agent B
Agent B ──SendMessageTool──→ Agent A
Agent C ──SendMessageTool──→ All
```

`SendMessageTool` 允许 Agent 之间发送消息，实现协作。

### 清理

```typescript
// init.ts 中注册清理
registerCleanup(async () => {
  const { cleanupSessionTeams } = await import('../utils/swarm/teamHelpers.js')
  await cleanupSessionTeams()
})
```

会话结束时自动清理所有创建的团队。

---

## 4. Agent 定义 (`tools/AgentTool/loadAgentsDir.js`)

用户可以在项目中定义自定义 Agent 类型：

```typescript
type AgentDefinition = {
  name: string
  description: string
  // Agent 的系统提示
  // 可用的 Tool 集
  // 其他配置
}

type AgentDefinitionsResult = {
  definitions: AgentDefinition[]
  // ...
}
```

自定义 Agent 在 `AgentTool` 的 `prompt()` 中向模型描述可用的 Agent 类型。

---

## Agent 间通信机制

### Task Notification (XML)

工人 Agent 通过标准输出发送 XML 格式的任务通知：

```xml
<task-notification>
  <agent-id>worker-1</agent-id>
  <status>completed</status>
  <result>找到了 3 个 bug</result>
</task-notification>
```

协调器解析这些通知来追踪进度。

### Scratchpad 目录

```typescript
import { getScratchpadDir, isScratchpadEnabled } from './utils/permissions/filesystem.js'
```

Agent 之间可以通过共享的 scratchpad 目录交换文件，避免通过消息传递大量数据。

---

## 后台 Agent

Agent 可以在后台运行：

```
主 Agent 发起后台 Agent
  │
  ├── 后台 Agent 独立执行
  │     ├── shouldAvoidPermissionPrompts = true（不能弹 UI）
  │     ├── 权限需求被自动拒绝
  │     └── 结果通过 TaskOutputTool 获取
  │
  └── 主 Agent 继续与用户交互
```

### 关键约束

```typescript
// ToolUseContext 中
shouldAvoidPermissionPrompts?: boolean  // 后台 Agent = true
```

后台 Agent **不能弹出权限确认**——所有需要用户确认的操作会被自动拒绝。这是安全设计：后台进程不应该干扰用户。

---

## Worktree 隔离

```
EnterWorktreeTool
  │
  ▼
创建 Git Worktree (.claude/worktrees/<name>/)
  │
  ├── 新的工作目录
  ├── 新的 Git 分支
  └── 文件完全隔离
  │
  ▼
Agent 在 Worktree 中工作
  │
  ▼
ExitWorktreeTool
  ├── keep → 保留 Worktree
  └── remove → 删除 Worktree
```

Worktree 为 Agent 提供了文件系统级别的隔离，多个 Agent 可以同时修改代码而不冲突。